home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / getpwent.man < prev    next >
Encoding:
Text File  |  1991-01-09  |  5.9 KB  |  199 lines
  1.  
  2.  
  3.  
  4. GETPWENT              C Library Procedures               GETPWENT
  5.  
  6.  
  7.  
  8. NNAAMMEE
  9.      getpwent, getpwnam, getpwuid, setpassent, setpwfile,
  10.      setpwent, endpwent - get password file entries
  11.  
  12. SSYYNNOOPPSSIISS
  13.      ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  14.      ##iinncclluuddee <<ppwwdd..hh>>
  15.  
  16.      ssttrruucctt ppaasssswwdd **ggeettppwweenntt(())
  17.  
  18.      ssttrruucctt ppaasssswwdd **ggeettppwwnnaamm((llooggiinn))
  19.      cchhaarr **llooggiinn;;
  20.  
  21.      ssttrruucctt ppaasssswwdd **ggeettppwwuuiidd((uuiidd))
  22.      uuiidd__tt uuiidd;;
  23.  
  24.      iinntt sseettppaasssseenntt((ssttaayyooppeenn))
  25.      iinntt ssttaayyooppeenn;;
  26.  
  27.      vvooiidd sseettppwwffiillee((ffiillee))
  28.      cchhaarr **ffiillee;;
  29.  
  30.      iinntt sseettppwweenntt(())
  31.  
  32.      vvooiidd eennddppwweenntt(())
  33.  
  34. DDEESSCCRRIIPPTTIIOONN
  35.      _G_e_t_p_w_e_n_t, _g_e_t_p_w_u_i_d, and _g_e_t_p_w_n_a_m each return a pointer to a
  36.      structure containing the broken-out fields of a line in the
  37.      password file.  This structure is defined by the include
  38.      file <pwd.h>, and contains the following fields:
  39.  
  40.           struct passwd {
  41.                char *pw_name;           /* user name */
  42.                char *pw_passwd;         /* encrypted password */
  43.                uid_t     pw_uid;        /* user uid */
  44.                gid_t     pw_gid;        /* user gid */
  45.                time_t    pw_change;     /* password change time */
  46.                char *pw_class;          /* user access class */
  47.                char *pw_gecos;          /* Honeywell login info */
  48.                char *pw_dir;            /* home directory */
  49.                char *pw_shell;          /* default shell */
  50.                time_t    pw_expire;     /* account expiration */
  51.           };
  52.  
  53.      These fields are more completely described in _p_a_s_s_w_d(5).
  54.  
  55.      _G_e_t_p_w_n_a_m and _g_e_t_p_w_u_i_d search the password database for a
  56.      matching user name or user uid, respectively, returning the
  57.      first one encountered.  Identical user names or user uids
  58.      may result in undefined behavior.
  59.  
  60.  
  61.  
  62.  
  63. Sprite v1.0             February 23, 1989                       1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GETPWENT              C Library Procedures               GETPWENT
  71.  
  72.  
  73.  
  74.      _G_e_t_p_w_e_n_t sequentially reads the password database and is
  75.      intended for programs that wish to step through the complete
  76.      list of users.
  77.  
  78.      All three routines will open the password file for reading,
  79.      if necessary.
  80.  
  81.      _S_e_t_p_w_f_i_l_e changes the default password file to _f_i_l_e, thus
  82.      allowing the use of alternate password files.
  83.  
  84.      _S_e_t_p_a_s_s_e_n_t opens the file or rewinds it if it is already
  85.      open.  If _s_t_a_y_o_p_e_n is non-zero, file descriptors are left
  86.      open, significantly speeding up subsequent calls.  This
  87.      functionality is unnecessary for _g_e_t_p_w_e_n_t as it doesn't
  88.      close its file descriptors by default.  It should also be
  89.      noted that it is dangerous for long-running programs to use
  90.      this functionality as the password file may be updated by
  91.      _c_h_p_a_s_s(1), _p_a_s_s_w_d(1), or _v_i_p_w(8).
  92.  
  93.      _S_e_t_p_w_e_n_t is identical to _s_e_t_p_a_s_s_e_n_t with an argument of
  94.      zero.
  95.  
  96.      _E_n_d_p_w_e_n_t closes any open files.
  97.  
  98.      These routines have been written to ``shadow'' the password
  99.      file, e.g.  allow only certain programs to have access to
  100.      the encrypted password.  This is done by using the
  101.      _m_k_p_a_s_s_w_d(8) program, which creates _n_d_b_m(3) databases that
  102.      correspond to the password file, with the single exception
  103.      that, rather than storing the encrypted password in the
  104.      database, it stores the offset in the password file where
  105.      the encrypted password may be found.  _G_e_t_p_w_e_n_t, _g_e_t_p_w_n_a_m,
  106.      and _g_e_t_p_w_u_i_d will use the _n_d_b_m files in preference to the
  107.      ``real'' password files, only reading the password file
  108.      itself, to obtain the encrypted password, if the process is
  109.      running with an effective user id equivalent to super-user.
  110.      If the password file itself is protected, and the _n_d_b_m files
  111.      are not, this makes the password available only to programs
  112.      running with super-user privileges.
  113.  
  114. FFIILLEESS
  115.      /etc/passwd
  116.  
  117. SSEEEE AALLSSOO
  118.      getlogin(3), getgrent(3), ndbm(3), passwd(5)
  119.  
  120. DDIIAAGGNNOOSSTTIICCSS
  121.      The routines _g_e_t_p_w_e_n_t, _g_e_t_p_w_n_a_m, and _g_e_t_p_w_u_i_d, return a null
  122.      pointer on EOF or error.  _S_e_t_p_a_s_s_e_n_t and _s_e_t_p_w_e_n_t return 0
  123.      on failure and 1 on success.  _E_n_d_p_w_e_n_t and _s_e_t_p_w_f_i_l_e have no
  124.      return value.
  125.  
  126.  
  127.  
  128.  
  129. Sprite v1.0             February 23, 1989                       2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GETPWENT              C Library Procedures               GETPWENT
  137.  
  138.  
  139.  
  140. BBUUGGSS
  141.      All information is contained in a static buffer which is
  142.      overwritten by each new call.  It must be copied elsewhere
  143.      to be retained.
  144.  
  145.      Intermixing calls to _g_e_t_p_w_e_n_t with calls to _g_e_t_p_w_n_a_m or
  146.      _g_e_t_p_w_u_i_d, or intermixing calls to _g_e_t_p_w_n_a_m and _g_e_t_p_w_u_i_d,
  147.      after using _s_e_t_p_a_s_s_e_n_t to require that file descriptors be
  148.      left open, may result in undefined behavior.
  149.  
  150.      The routines _g_e_t_p_w_e_n_t, _e_n_d_p_w_e_n_t, _s_e_t_p_a_s_s_e_n_t, and _s_e_t_p_w_e_n_t
  151.      are fairly useless in a networked environment and should be
  152.      avoided, if possible.
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0             February 23, 1989                       3
  196.  
  197.  
  198.  
  199.